Knife4j OpenAPI 3.0 完整配置指南

快速开始

1. pom.xml 依赖配置

<!-- Knife4j OpenAPI 3.0：Swagger 增强版，API 文档生成 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

2. 配置类（Knife4jConfig.java）

package com.zwnsyw.zwwwspringbootbasetemplate.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("项目接口文档")
                        .version("1.0.0")
                        .description("RESTful API 接口说明文档")
                        .contact(new Contact()
                                .name("开发者")
                                .url("https://example.com")
                                .email("dev@example.com"))
                        .license(new License()
                                .name("Apache 2.0")
                                .url("http://www.apache.org/licenses/LICENSE-2.0")));
    }
}

3. application.yml 配置

server:
  port: 8080
  servlet:
    context-path: /api

knife4j:
  enable: true

访问文档

• Knife4j 文档：http://localhost:8080/api/doc.html
• Swagger UI：http://localhost:8080/api/swagger-ui.html
• OpenAPI JSON：http://localhost:8080/api/v3/api-docs

注意：因为配置了 context-path: /api，所以所有地址都需要加上 /api 前缀

在 Controller 中使用注解

package com.zwnsyw.zwwwspringbootbasetemplate.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/user")
@Tag(name = "用户管理", description = "用户相关接口")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "获取用户详情", description = "根据用户ID获取用户信息")
    public String getUserById(@PathVariable Long id) {
        return "User: " + id;
    }

    @PostMapping
    @Operation(summary = "创建用户", description = "创建一个新的用户")
    public String createUser(@RequestBody UserDTO user) {
        return "Created user: " + user.getName();
    }
}

class UserDTO {
    private String name;
    private String email;

    // getter/setter
}

常用注解说明

环境配置

application-dev.yml（开发环境）

knife4j:
  enable: true

application-prod.yml（生产环境）

knife4j:
  enable: false

故障排查

访问 404

问题：访问 http://localhost:8080/doc.html 返回 404

解决：

1. 检查 context-path 配置
2. 使用正确的 URL：http://localhost:8080/api/doc.html
3. 确保应用已启动

无法看到接口

问题：文档页面显示但没有接口

解决：

1. 确认 Controller 类加了 @RestController 或 @Controller 注解
2. 确认方法加了 @GetMapping 等 HTTP 方法注解
3. 添加 @Tag 和 @Operation 注解来增强文档

依赖冲突

问题：无法识别 io.swagger.v3 包

解决：

1. 确保 pom.xml 中使用的是 knife4j-openapi3-spring-boot-starter（不是 openapi2）
2. 清除 Maven 缓存：rm -rf ~/.m2/repository/com/github/xiaoymin/
3. 重新下载：mvn clean install -DskipTests

最佳实践

1. 在生产环境禁用文档

   knife4j:
     enable: ${KNIFE4J_ENABLE:false}
   

2. 为所有 Controller 添加 @Tag

   @RestController
   @Tag(name = "功能模块", description = "功能说明")
   public class DemoController { }
   

3. 为所有接口添加 @Operation

   @GetMapping("/{id}")
   @Operation(summary = "简短描述", description = "详细描述")
   public String demo(@PathVariable Long id) { }
   

4. 为复杂参数添加 @Schema

   @Schema(description = "用户ID")
   private Long userId;
   

完整示例项目结构

src/main/java/com/zwnsyw/zwwwspringbootbasetemplate/
├── config/
│   └── Knife4jConfig.java          # Knife4j 配置
├── controller/
│   ├── UserController.java         # 用户接口
│   └── ProductController.java      # 产品接口
├── dto/
│   ├── UserDTO.java
│   └── ProductDTO.java
└── ZwwwSpringBootBaseTemplateApplication.java

src/main/resources/
├── application.yml                 # 主配置
├── application-dev.yml             # 开发配置
└── application-prod.yml            # 生产配置

项目分区导航：⬅️ 00-接口文档 | 01-Knife4j OpenAPI 3.0 完整配置指南 | ➡️ 01-缓存使用最佳实践指南